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About This Book 


This book, as well as the other books in the upgrade package, contains 
programming information that is new to or different from the information in the IBM' 
Operating System/2' (OS/2') Programming Tools and Information Version 1.2. library 
(part number 6024929). In addition, information from the OS/2 Programming Tools 
and Information Version 1.2 Technical Update (part number 64F1705) is included in 
this upgrade package. 

The upgrade describes features added by the OS/2 Version 1.3 product, and amends 
some of the information that was published with OS/2 Version 1.2. 


How To Use This Book 

This book contains a section for each of the following books: 

Book Title Book Number 

I/O Subsystems and Device Support: Volume 1 

Device Drivers 64F0282 

I/O Subsystems and Device Support: Volume 2 

Presentation Driver Interfaces 64F0283 

Only those chapters of the Version 1.2 book that are changed by the Version 1.3 
producl are included herein. The chapter numbers and titles are the same as those 
in the Version 1.2 book. As a convenience, the beginning of each chapter in this 
book provides a summary of changes for that chapter. 


Who Should Read This Book 

This book is for application designers and programmers who are using the 
components of the IBM OS/2 Version 1.2/1. 3 Programming Tools and Information 
Technical Upgrade package. The reader is assumed to be familiar with the services 
of OS/2. 


* Trademark of the IBM Corporation 
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Chapter 2. Device Driver Overview 


Summary of Changes 


New 

Updated 

Section Title 


V 

Device Driver INIT-Time Function Call Summary 


Device Driver INIT-Time Function Call Summary 

On page 2-8, add the following: 

DosGetlnfoSeg Get Address of System Variables Segment 
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Request Packets 

On page 4-3, add the following error code to Table 4-3 (Status-Field Error Codes): 
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Chapter 5. Device Helper Services 


Summary of Changes 


New 

Updated 

Section Title 


V 

DevHIp Services and Function Codes 


V 

DevHIp Services and Device Contexts 

V 


DispMsg 


V 

MonWrite 

V 


VideoPause 


DevHIp Services and Function Codes 

On page 5-2, in the table of DevHIp Services and Function Codes, change code 38 to 
3A, and add the following services: 

VideoPause 3C Suspend/resume video active threads 

DispMsg 3D Display message (for base device drivers) 


DevHIp Services and Device Contexts 

On page 5-4, in the table of DevHIp Service Modes, change code 38 to 3A, and add 
the following services: 

DevHIp Service Code Kernel Interrupt User In it 

VideoPause 3C * * * 

DispMsg 3D * 

On page 5-5, add the DispMsg and VideoPause services to 10. System Services. 


DispMsg 
Display Message 

This function displays a message from a base device driver on the system console. 


Processing 


MOV 

ES.SEG Msg Table 

; ES 

MOV 

DI, OFFSET Msg Table 

; DI 

XOR 

BX,BX 

; BX 

MOV 

DL,DevHlp_DispMsg 


CALL 

[Device_Help] 



segment of message table 
offset of message table 
Reserved (must be 0) 


Results 


None. 
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Remarks 

The message is not displayed immediately but is queued until system initialization 
retrieves it from the system message file. 

The structure of the message table is: 

WORD Message ID 

WORD Number of fill-in items 

DWORD Pointer to first fill-in item of ASCIIZ string 
DWORD Pointer to second fill-in item of ASCIIZ string 


DWORD Pointer to last fill-in item of ASCIIZ string 

If an error message is displayed, and pausenoerror=no is not contained in 
config.sys, the user is prompted to press any key to continue. 


MonWrite 

Give Data to Monitors 

On page 5-29, replace the contents of the entire page with the following: 


Purpose 

Processing 


Results 


Remarks 


MonWrite passes data records to the monitors for filtering. 


LDS SI ,data_record_offset 

record in DS 

MOV CX, count 

MOV AX ,moni tor_handl e 

returned from 

MOV DI ,mi 1 1 i secondjii gh 
MOV BX ,mi 11 i second II ow 
MOV DH, waitjlag 
CALL [Device_Help] 


; Offset of data 

; Byte count of data record 
; Handle for chain 

; Previous MonitorCreate call 
; High word of milliseconds 
; Low word of milliseconds 

; Wait/Nowait/Waitjimeout flag MOV DL,DevHlp_MonWrite 


'C' Clear if OK 
AX = 0 

'C' Set if error 
AX = error code 

Invalid monitor handle 
Not enough memory 
Call interrupted 
Error semaphore timeout 


This function may be called at task time or interrupt time, in either the OS/2 mode or 
DOS mode. Waitjlag is set to 0 if the MonWrite request occurs at task or user time 
and the device driver indicates that the monitor dispatcher do the synchronization. 
That is, if waitjlag is set to 0, the device driver waits until the data can be placed 
into the monitor chain before the monitor dispatcher returns to the device driver. If 
waitjlag is set to 1, the device driver does not wait; and if the data cannot be placed 
into the monitor chain, the monitor dispatcher will return immediately with the 
appropriate error. Waitjlag must be set to 1 if the MonWrite request occurs at 
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interrupt time. Wait_flag is set to 2 if the MonWrite request occurs at task or user 
time, and the device driver indicates that the monitor dispatcher do the 
synchronization for the time in milliseconds specified in DI:BX. 

The DS register must be set to the device-driver data segment. 

The error, NOT ENOUGH MEMORY, will be returned to the device driver when the 
MonWrite call is made and the monitors are not able to receive the data. If this 
condition occurs at interrupt time, an overrun occurred. If it occurs at task (or user) 
time, the process can block. 

The error, NOT ENOUGH MEMORY, also will be returned to the device driver when 
a flush record, sent to the monitors by a previous MonFlush call, was not returned to 
the device driver. 

If the thread on which the device driver calls MonWrite blocks (the device driver 
specified the wait option) and is awakened because the process that owns the 
thread is terminating, a call-interrupted error is returned to the device driver. The 
device driver must return the error to the caller so that the process can complete 
termination. 

Each call to MonWrite will send a single complete record. The data sent by this call 
is considered to be a complete record. A data record must not be longer than two 
bytes less than the length of the device driver's monitor chain buffer. 

The state of the interrupt flag is not preserved across calls to DevHIp. 

See Chapter 8, “Character Device Monitors,” for more information about the use of 
this function. 


VideoPause 

Suspend/Resume Video Active Threads 

This function is called by device drivers when the controller reports a DMA overrun. 
VideoPause starts or stops high-priority threads. This halts threads using the CPU 
for video transfers, which allows the diskette DMA to complete termination properly. 


Processing 

MOV AL,on_or_off 


MOV DL,DevHlp_VideoPause 
CALL [Device_Help] 

Results 

None. 

Remarks 

Use this function after a retry has failed. Turn VideoPause on just long enough to 
accomplish the transfer; otherwise, impairment of the system could occur. If 
multiple device drivers turn VideoPause on, it is not turned off until all device 
drivers have turned it off. 


VideoPause flag 
= 0 off 
< > 0 on 
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Chapter 6. Device Drivers 


Summary of Changes 


New 

Updated 

Section Title 


V 

Mouse Device Overview 


V 

Inter-Device Drive Communication (IDC) Interface 
Description 


V 

Keystroke Monitors 


V 

The Printer Device Driver 


7 

Font Monitor Packet 

V 


Print-Monitor-Job Title Packet 

V 


Monitor-Job Title Packet 


Mouse Device Overview 

Note: Throughout this section, two terms, mouse and MOUSES, are used 
repeatedly. They are defined as follows: 

• Mouse: Any class of pointing device, unless otherwise noted. 

• MOUSES: A device-independent device driver. 

On page 6-37, replace the first paragraph with the following: 

The OS/2 Operating System provides support for a pointing device for both DOS 
mode and OS/2 mode applications. Two classes of pointing devices are supported: 
relative and absolute. A relative pointing device reports relative motion (how far it 
has moved). An example of a relative pointing device is a mouse or a track ball. An 
absolute pointing device reports absolute positions within some predefined device 
space. With an absolute pointing device, there is no real concept of relative motion. 
An example of an absolute pointing device is a touch-sensitive screen. The 
following components provide pointing-device support: 

• A mouse device driver 

• A mouse router 

• A base mouse subsystem 

• A pointer draw device driver. 


Inter-Device-Driver Communication (IDC) Interface Descriptions 

Starting on page 6-41, replace the IDC interface descriptions from the 
“Device-Independent Mouse Device IDC Description” up to (but not including) “OS/2 
Mode Mouse Support” at the top of page 6-44, with the following: 

This section describes the supported device-independent and dependent device 
driver IDC interfaces. For all IDC requests, follow these steps: 

1. Load AX with the request number. 

2. Initialize required data areas. 

3. Load other required registers. 
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4. Load DS with the data segment/selector of the called device driver. 

5. Load ES with the data segment/selector of the calling device driver. 

6. Execute a far call to the IDC entry point in the other device driver. 

7. Examine the carry flag when the far call is returned. Carry set indicates that the 
request failed. Carry clear indicates that the request was processed. 

All registers not explicitly listed contain undefined values. Register values are not 
preserved across IDC requests, with exception to values for segment registers. The 
state of the interrupt flag must be preserved across all IDC requests. 

Use caution when loading DS and ES, and when executing the far call. These 
operations are processor-mode dependent. AttachDD will return both real- and 
protect-mode entry points, as well as segment and selector values for the data 
segment of the attached-to device driver. 

MOUSES IDC Interface 

The IDC provided by MOUSES supports the following: 

• Process_Packet 

• Disable_Support 

• Process_Absolute. 


Process_Packet 

This request is issued by the device-dependent device driver to process a 
relative-pointing-device event, usually from a mouse device. Before requesting 
Process_Packet, issue an end-of-interrupt (EOI), and place the pointing device in a 
disabled state. For a description of a disabled state, see “Disable_Device” on 
page 15 in this book. When necessary, use MOUSES to return the device to an 
enabled state. Process_Packet is issued only when the pointing device is enabled. 
For a discussion of interrupt processing, see “Interrupt Processing” on page 6-40 of 
the OS/2 Version 1.2 I/O Subsystems and Device Support, Volume 1 Device Drivers 
book. 

Input: 


AX = Process_Packet function code, 0001 H. 

Common-event bufler initialized. 

The offset of the common-event buffer was passed on the 
Read_Enable request. This data buffer is used to pass both relative 
and absolute pointing-device events. When the device driver issues 
a Process_Packet request, the buffer has the following format: 


Event_Data 

Struc 



Event 

dw 


; Description of event* 

Col_Motion 

dw 

? 

; Relative column motion. 

Row_Motion 

dw 

? 

; Relative row motion. 

Event Data 

Ends 




Before the device driver makes the request, initialize the buffer. 
Note that positive motion is up and to the right. Up can also be 
viewed as moving a mouse device away from the user. Negative 
motion is the opposite of positive. 

Output: No specific output for request. 
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Disable_Support 


This request is used by the device-dependent device driver to inform MOUSES that it 
has Deinstalled. When the request is received, MOUSES enters a disabled state. It 
returns the error, DEVICE NOT READY, for subsequent requests from the system. 

Do not issue this request under normal circumstances. 

Input: 


AX = Disable_Support function code, 0002H. 
Output: No specific output for the request. 


Process_Absolute 

This request is issued by the device-dependent device driver to process an 
absolute-pointing device event, usually from a touch-sensitive screen. Before 
requesting Process_Absolute, issue an EOI, and place the pointing device in a 
disabled state. For a description of a disabled state, see "Disable_Device” on 
page 15 in this book. When necessary, use MOUSES to return the device to an 
enabled state. Process_Absolute is issued only when the pointing device is 
enabled. For a discussion of interrupt processing, see “Interrupt Processing" on 
page 6-40 of the OS/2 Version 1.2 I/O Subsystems and Device Support, Volume 1 
Device Drivers book. The reported event is mapped into the current display mode 
and appears to the system to be a mouse event. 

Input: 


AX = Process_Absolute function code, 0003H. 

Common-event buffer initialized. 

The offset of the common-event buffer was passed on the 
Read_Enable request. This data buffer is used to pass both relative 
and absolute pointing-device events. When issuing a 
Process_Absolute request, the buffer has the following format: 


EventJ)ata 

Struc 



Event 

dw 

? 

; Description of event. 

Row_Pos 

dw 

? 

; Row position of event. 

Col_Pos 

dw 

? 

; Col position of event. 

Row_Size 

dw 

? 

; Number of row units. 

Co1_Size 

dw 

? 

; Number of column units. 

Event Data 

Ends 




MOUSES uses Row_Size and Col_Size to map the absolute event into 
the current display mode. These values should reflect the maximum 
allowed position that could be reported. All values are zero-based. 
The event field should never indicate that motion was associated 
with the event. MOUSES will determine if motion occurred. The 
upper-left corner of the device should be reported as location 0,0. 

Initialize the buffer before making the request. 

Output: No specific output for the request. 
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Device-Dependent Device Driver IDC Interface 

The IDC provided by the device-dependent device driver must support the following 
requests: 

• Query_Config 

• ReadEnable 

• ReadDisable 

• Enable_Device 

• Disable_Device. 


Query_Config 

This request is issued by MOUSES and determines the operating characteristics of 
the attached hardware. The format follows. 

Input: 


AX = Query_Config function code, 0001H. 

Dl = Offset in mouse data segment of where to write the 
configuration data. Note that ES was loaded with the MOUSES data 
segment/selector prior to the request. The configuration data has 


the following format: 


Config_Data 

Struc 



Length 

dw 

? 

Total length in bytes (6) 

Num_Mics 

db 

? 

Device resolution in mickeys/centimeter. 

Num Butt 

db 

? 

Number of buttons (up to 7 supported) 

DevJRQ 

db 

? 

Device IRQ level 

Mouse_Type 

db 

? 

Type of mouse attached: 




0 = Unknown 

1 = Bus mouse 

2 = Serial mouse 



! 

! 

3 = Inport mouse 

4 = PS/2 inboard 

5-255 = Reserved 

Config_Data 

Ends 




Initialize the Length field to 6 before issuing the request. An 
absolute pointing device, such as a touch-sensitive screen, reports a 
mouse type of zero (unknown). The Num_Mics field for an absolute 
device should reflect some reasonable measure of the number of 
device units per centimeter. 

Output: Configuration data structure filled if no errors. 


Read_Enable 

This request serves two purposes. It gives the offset of the common-event buffer in 
the MOUSES data segment. This offset should be saved. It also informs the 
device-dependent device driver that it can start sending event data to MOUSES 
using the Process_Packet and Process_Absolute requests. The device-dependent 
device driver also should attach itself to MOUSES, using the Device Helper function 
AttachDD, when it receives this request. 

Input: 


AX = Read Enable function code, 0002H. 
Dl = Offset to common-event buffer. 


The common-event buffer resides in the MOUSES data segment. To 
address it, use the MOUSES data segment/selector value, depending 
on the processor mode, returned on the AttachDD call. The 
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common-event buffer has enough space to format either a relative or 
absolute event. For the two common-event buffer formats, see 
“Process_Packet” on page 12, and “Process_Absolute" on page 13 
in this book. 

Output: No specific output for the request. 


Read_Disable 

This request is issued by MOUSES when it no longer accepts Process_Packet or 
Process_Absolute requests. References to the common-event buffer should be 
discontinued. However, MOUSES may enable the interface again by sending 
another Read_Enable request. Normally this request is not issued. 

Input: 

AX = Read_Disable function code, 0003H 
Output: No specific output for the request. 

Enable_Device 

This request is used by MOUSES when resetting a pointing device to an enabled 
state. Process_Packet and Process_Absolute requests are made to MOUSES when 
a pointing device is in an enabled state. Receipt of an Enable_Device request is not 
considered an error if the pointing device is already enabled. 

Input: 

AX = Enable_Device function code, 0004H. 

Output: No specific output for the request. 

Disable_Device 

This request is used by MOUSES when placing a pointing device in a disabled state. 
Upon completion of this request, no Process Packet or Process_Absolute requests 
are to be made to MOUSES until an Enable_Device request is received. There is no 
requirement that the hardware itself be disabled; only that no Process_Packet or 
Process_Absolute requests be issued. Receipt of a Disable_Device request is not 
considered an error if the pointing device is already disabled. 

Input: 


AX = Disable_Device function code, 0005H. 
Output: No specific output for the request. 


Keystroke Monitors 

An application operating with OS/2 Version 1.2 and Version 1.3 cannot register a 
keyboard monitor for a Presentation Manager session. The following information 
clarifies this restriction. 

On page 6-66, replace the second paragraph under Keystroke Monitors with the 
following: 

When DosMonReg is issued with keyboard devices, the INDEX parameter indicates 
which OS/2 session the caller requested the monitor to be registered on. Note that 
the INDEX parameter indicates an OS/2 session from 0 to 15 (see DosGetlnfoSeg). 

An INDEX parameter value of -1 indicates that the session of the calling thread is 
being requested. If the caller requests either the Presentation Manager session or 
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the DOS mode session, a MONITORS NOT SUPPORTED error is returned. For both 
of these sessions, the error return code will be generated, regardless of the caller's 
specific usage of the INDEX parameter (explicit/implicit). 


The Printer Device Driver 

On page 6-128, replace the table (under the first paragraph) with the following: 

PRINT01.SYS (part of BaseddOl .sys) supporting parallel port adapters on Family 

One bus machines. 

PRINT02.SYS (part of Basedd02.sys supporting parallel port adapters on 

machines containing Micro Channel 
Architecture. 


Font Monitor Packet 

On page 6-143, replace the table (under the first paragraph) with the following: 


Table 6-24. Monitor Font Packet 

System File Number 

WORD 

Command Byte 

BYTE 

Reserved, Set to 0 

BYTE 

Reserved, Set to 0 

BYTE 

Reserved, Set to 0 

BYTE 


Print-Monitor-Job Title Packet 

On page 6-146, (after “Monitor Status Packet”) add the following new information: 

A print-monitor-job title packet passes the name of the file being printed to all 
monitors registered with the printer device driver. The flags are defined in Figure 1 
on page 17. 
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Monitor Flags 


Device-Driver 

Dependent 


Byte 0 


Byte 1 


| Open 
Close 
Flush 


Printer Font Monitor 
Buffer Command Response 
Code Page Command Processed 
I NT 17H Code Page Request 
Status 
Reserved 
Job Title 


■•Reserved^ 


■•Reserved^ 


Figure 1. Monitor Packet Flags 


Monitor-Job Title Packet 

When the job title bit is set to 1 (byte 1, bit 5), it indicates the monitor buffer is a job 
title packet from the printer device driver. In this case, the next bytes are: 


Monitor-Job Title Packet 

System File Number 

WORD 

Job Title Length 

WORD 

Job Title Buffer 

BYTES 


The job title length field includes the null character. The job title buffer is 
terminated with the null character. 

The job title buffer field contains byte 6 through byte 131. 
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Chapter 7. Generic lOCtl Commands 


Summary of Changes 


New 

Updated 

Section Title 

V 


Generic lOCtl Examples 


V 

Category 1, Function 53H 


V 

Category t , Function 73H 


V 

Category 4, Function 50H 


V 

Category 4, Function 56H 

V 


Category 5, Function 4DH 

V 


Category 5, Function 4EH 

V 


Category 5, Function 6EH 


V 

Category 8, Function 43H 


V 

Category 8, Function 63H 


Generic lOCtl Examples 

On page 7-3, add the following to the list of categories and functions for the 
GENERIC lOCtl request: 

CAT FUNCTION DESCRIPTION 


47H 

Reserved 

4BH 

Reserved 

4CH 

Reserved 

4DH 

Set Printer Job Title 

4EH 

Set Printer Timeout Value 

4FH 

Reserved 

67H 

Reserved 

6BH 

Reserved 

6CH 

Reserved 

6DH 

Reserved 

6EH 

Return Printer Timeout Value 

6FH 

Reserved 
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Category 1 — 
Function 53H 


On page 7-17, change the Flags3 settings to the following: 

Note Bit Meaning 

10 3-4 Extended Hardware Buffering 

Bit 4 Bit 3 

0 0 Not Supported; ignored. 

No change to FIFO state. 

0 1 Extended Hardware Buffering 

DISABLED 

1 0 Extended Hardware Buffering 

ENABLED 

1 1 Automatic Protocol Override 


Category 1 — 
Function 73H 


On page 7-44, change the definition of Flags3, bits 3-4 to the following: 

Extended Hardware Buffering 
Bit 4 Bit 3 

0 0 Not supported 

0 1 Extended Hardware Buffering DISABLED 

1 0 Extended Hardware Buffering ENABLED 

1 1 Automatic Protocol Override 


Category 4 — 
Function 50H 


On page 7-56, replace the Parameter Packet Format table with the following: 


Field 

Length 

Code Page Translation Table 

OTHER 


Category 4 — 
Function 56H 


On page 7-72, under Remarks add the following: 

When hot key ID FFFFh is set, Alt + Ctrl + Del, Alt + Esc, and Alt + Ctrl + NumLock 
keys are disabled. You can reinstate these keys by reissuing lOCtl 56H (Set Session 
Manager Hot Key). 
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Category 5 — 
Function 4DH 


Purpose 

Set print-job title. 

Parameter Packet Format 


Field 

Length 

Command Information 

BYTE 


Data Packet Format 


Field 

Length 

Length 

WORD 

Address of ASCIIZ job title 

DWORD 


Where: 


Returns 


Remarks 


Command Information 

is reserved and must be set to zero. 

Length 

is the length of the buffer containing the print-job title. This includes the 
terminating null character, but excludes the length field. 

Address of Job Title 

is the address of the ASCIIZ string containing the print-job title. A null character 
terminates the ASCIIZ string. 


in the kernel request-packet status field: 

0100H Completed successfully. 

8113H Invalid parameter if the address of data packet is invalid. 

8113H Invalid parameter if the address of the ASCIIZ string is invalid. 


If the ASCII string has more than 126 bytes, the printer device driver truncates it to 
the first 125 bytes, plus 1 byte for the null character. 


Category 5 — 

Function 4EH 

Purpose 

Set printer-timeout value. 
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Parameter Packet Format 


Field 

Length 

Command Information 

BYTE 


Data Packet Format 


Field 

Length 

Timeout Value in Seconds 

WORD 


Where: 


Returns 


Remarks 


Command Information 

is reserved and must be set at zero. 

Timeout Value 

is the length of time, in seconds, that the printer device driver waits for a 
hardware interrupt to occur. 


in the kernel request-packet status field. 

0100H Completed successfully 

8113H Invalid parameter if the data-packet address is invalid. 


This lOCtl informs the base, physical, printer device driver of the length of time (in 
seconds) to wait for a hardware interrupt before a print request is canceled. 

Valid timeout values range between 0 and 65535 seconds. An application setting 
this value must also issue PRFWriteProfileString to update the OS2SYS.INI file. 


Category 5 — 

Function 6EH 

Purpose 

Return printer timeout value. 

Parameter Packet Format 


Field 

Length 

Command Information 

BYTE 


Data Packet Format 


Field 

Length 

Timeout Value in Seconds 

WORD 
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Where: 


Command Information 

is reserved and must be set to zero. 

Timeout Value 

is the length of time, in seconds, that the printer device driver waits for a 
hardware interrupt to occur. 


Returns 


Remarks 


in the kernel request status field: 

0100H Completed successfully 

8113H Invalid parameter if the data-packet address is invalid. 


Valid timeout values range between 0 and 65535 seconds. 


Category 8 — 

Function 43H 

Purpose 

On page 7-143, under Device type, add the following: 

Value Meaning 

8 R/W optical disk 

On page 7-143, under Device attributes, change the device attribute bits to the 
following: 

Bit Description 

0 Removable media flag, if this bit is set to 1 , the media cannot be 

removed. If this bit is set to 0, the media is removable. 

1 Changeline flag. If this bit is set to 1, the device support can determine if 
the media was removed since the last I/O operation. Query whether the 
media has changed by calling the device driver strategy command 
1H/Media Check. 

If this bit is set to 0, then the device driver can return the value 0 (unsure 
if media has changed) from the Media Check call. 


Category 8 — 

Function 63H 

Purpose 

On page 7-148, under Device type, add the following: 

Value Meaning 

8 R/W optical disk 

On page 7-149, under Device attributes, change the device attribute bits to the 
following: 
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Bit Description 

0 Removable media flag. If this bit is set to 1, the media cannot be 
removed. If this bit is set to 0, the media is removable. 

1 Changeline flag. If this bit is set to 1, the device support can determine if 
the media was removed since the last I/O operation. Query whether the 
media has changed by calling the device driver strategy command 
IH/Media Check. 

If this bit is set to 0, then the device driver can return the value 0 (unsure 
if media has changed) from the Media Check call. 
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Chapter 8. Character Device Monitors 


Summary of Changes 


New 

Updated 

Section Title 


V 

Monitoring Character Device Data Streams 


V 

Device Monitor Support Limitations 


Monitoring Character Device Data Streams 

OS/2 Version 1.2 and Version 1.3 do not allow an application to register a keyboard 
or mouse device monitor for a Presentation Manager session. The following 
information documents this restriction. 

On page 8-2, replace the second paragraph under Monitoring Character Device Data 
Streams with the following: 

The flow of data between a device driver and its device is called a data stream. The 
device driver defines the data streams for its device and associates the data it 
receives from a device or application with a particular data stream. Device drivers 
may have more than one data-stream model within or between sessions. For 
example, the keyboard device driver supports three different data-stream models 
for DOS mode, Presentation Manager, and OS/2 mode sessions. Of these, only the 
OS/2 mode data stream supports keystroke monitors. 

On page 8-2, replace the fifth paragraph under Monitoring Character Device Data 
Streams with the following: 

Just as device drivers define their data streams, they also determine how character 
monitors are chained. The keyboard and mouse device drivers, for example, 
support a monitor chain for each OS/2 mode session. The printer device driver 
supports two monitor chains for each physical printer device. See “Mouse Device 
Driver", “Console Device Drivers (Screen and Keyboard)”, and “The Printer Device 
Driver" sections in the original OS/2 Version 1.2 I/O Subsystems and Device 
Support, Volume 1 Device Drivers book for a description of how these device drivers 
support device monitors. 


Device Monitor Support Limitations 

On page 8-3, replace the first paragraph under Device Monitor Support Limitations 
with the following: 

Data streams for character devices may be monitored by a character-device 
monitor, only when the character device driver provides device monitor support. 
Applications, including both OS/2 mode and Presentation Manager applications, 
may monitor keystrokes and mouse clicks for all OS/2 mode sessions. However, the 
applications may not monitor keystrokes and mouse clicks for the Presentation 
Manager session. 
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On page 8-4, replace Figure 8-3, OS/2 Monitors and PM Applications, as follows: 



Remember that applications may no longer intercept keystrokes or mouse clicks 
associated with the Presentation Manager session through keystroke or mouse 
monitors. 
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Chapter 12. Mandatory Functions for All Devices 


Summary of Changes 


New 

Updated 

Section Title 


V 

GreQueryLogColorTable 


V 

GreCreateLogColorTable 


7 

GreEscape, DEVESC_GETCP 


V 

GreEscape, DEVESC_SETMODE 


V 

GreEscape, DEVESC_DRAFTMODE 


GreQueryLogColorTable 

On page 12-95, change CLR_NOINDEX in the description of the pArray parameter to 
QLCT_NOTLOADED. 


GreCreateLogColorTable 

On page 12-96, add the following to the options listed under flOptlons: 

LCOL SYSCOLOR This flag is set when the color data addressed by pData is for the 
system color table. For details see WinSetSysColors in the 
Programming Reference. 


GreEscape, DEVESC GETCP 

On page 12-123, delete all information about the DEVESC_GETCP subfunction of 
GreEscape. This escape code is not used and presentation drivers should not 
provide support for it. 


GreEscape, DEVESC_SETMODE 

In the GreEscape section of Chapter 12, add the following description of the 
DEVESC_SETMODE subfunction: 

The DEVESC_SETMODE escape code requests the presentation driver to set a 
specific mode of the output device. 

DEVESC_SETMODE is currently defined only for code-page mode (mode = 0). The 
action taken by the handling routine in the presentation driver depends upon what 
support the device provides for multiple code pages: 

1. If the device has the requested code page built into it, the handling routine 
issues the controls to select the code page. 

2. If the device supports downloaded code pages, the handling routine issues the 
calls and controls needed to load and select the requested code page. 

Note: DEVESC_SETMODE is metafiled and is recorded by the spooler. 
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Stack Frame 


hdc 

Device-context handle. 

lEscape 

DEVESCSETMODE 

clnCount 

Number of bytes pointed to by plnData. 

plnData 

Pointer to an ESCMODE structure: 


ulMode Identifies the mode that is to be changed. Defined values 
for ulMode are: 


0 Code page. 


abModedata The format and meaning of abModedata depends upon 
the value of ulMode. When ulMode = 0, abModedata 
contains the requested code page number expressed as 
a USHORT value. 

pcOutCount 

The handling routine should ignore this parameter. 

pOutData 

The handling routine should ignore this parameter. 


Return Codes 


The handling routine returns: 

DEVOK 

DEVESC_NOTIM PLEMENTED 
DEVESC_ERROR 


Successful. 

This escape code is not implemented. 
Error. 


GreEscape, DEVESCDRAFTMODE 

On page 12-120, add the following to the description of the DEVESC_DRAFTMODE 
subfunction: 

Note that the driver’s response to a call to GreDeviceQueryFonts is influenced 
by the current setting, off or on, of draft mode. If the device supports fonts that 
cannot be positioned to the nearest pel, the GreDeviceQueryFonts routine in the 
driver should only return details of these fonts when draft mode is on. 
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Chapter 13. Mandatory Functions for Display Devices 


Summary of Changes 


New 

Updated 

Section Title 


V 

GreDeviceSetAVIOFont 


V 

GreDeviceSetDCOrigin 


GreDeviceSetAVIOFont 

On page 13-9, the name, function number, and parameters of GreDeviceSetAVIOFont have been changed to 
allow the graphics engine to pass logical font information to the presentation driver. The function name is 
changed to GreDeviceSetAVIOFont2. Also, the Presentation Manager’s graphics engine has been modified 
so that calls to load or delete an image font for an AVIO presentation space are passed through the 
dispatch table to the handling routine for GreDeviceSetAVIOFont2. To minimize the impact on existing 
drivers, the default handling routine for GreDeviceSetAVIOFont2 removes the logical font information and 
redirects the call through the dispatch table to GreDeviceSetAVIOFont. 

The syntax for GreDeviceSetAVIOFont2 is: 

(BOOL) GreDeviceSetAVI0Font2 (hdc, pFat, pFontDef, 

lcid, plnstance, 1 Function) 

Differences between GreDeviceSetAVIOFont2 and GreDeviceSetAVIOFont are shown below. See 
GreDeviceSetAVIOFont on page 13-9 for a full description. 

pFat (PFATTRS) 

Pointer to a font attributes structure for the specified font. 

IFunction (ULONG) 

The symbolic name NGreDeviceSetAVIOFont2 identifies the function number in the low-order word of 

IFunction. 


GreDeviceSetDCOrigin 

On page 13-22, change the paragraph under Support to: 

This function must be supported by presentation drivers for display devices. Drivers for other device 
types must not include support for GreDeviceSetDCOrigin: these drivers must allow calls to this 
function to be directed, through the dispatch table, to the default handling routine. 
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Chapter 14. Simulated Functions 

Summary of Changes 


New 

Updated 

Section Title 


V 

GreSetupDC 


GreSetupDC 

On page 14-77, change the paragraph under Support to: 

This function is supported by the graphics engine and can be hooked by 
presentation drivers for display devices. Drivers for other device types must not 
hook GreSetupDC. 
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Chapter 15. Graphics Engine Internal Functions 


Summary of Changes 


New 

Updated 

Section Title 


V 

GreGetAttributes 


GreGetAttributes 

On page 15-24, note that this function can also return 
PMERR_UNSUPPORTED_ATTR. 


© Copyright IBM Corp. 1990 


35 










36 I/O Subsystems and Device Support 



The Queue Processor (Queue Driver) 

On page 17-20, replace the description of the Queue Processor (Queue Driver) with 
the following: 

Note: The Presentation Manager shell uses the term Queue Driver to identify the 
queue processor. 

A queue processor takes a spool file and prints it. Each queue has its own queue 
processor. The Presentation Manager system queue processor is supplied in the 
file PMPRINT.QPR. 

The following functions provide an interface to the queue processor: 

SpIQpCIose 

SpIQpControl 

SpIQpInstall 

SpIQpOpen 

SpIQpPrint 

SpIQpQueryDt. 

In addition to these functions, a visual interface is supplied through the 
SpIMessageBox entry point. 

You may supply queue processors of your own to support user data types, but any 
queue processor that you create must support the PM_Q_STD and PM_Q_RAW 
standard data types, also its file name must have the .QPR extension, and you must 
export the functions listed above. 

How a Queue Processor Prints 

The method used by the queue processor to write data to the printer depends on the 
data type: 

• PM_Q_STD Data is written to the printer using the API: 

Action 

Opens a DC for the printer using DevOpenDC and enables it 
as an OD_DIRECT device for PM_Q_STD data. 

Issues Escape(DEVESC_STARTDOC). 

Writes data, which is in metafile format, to DC. 

Starts a journal file. 

Processes and journals each call as it is passed by the 
queue processor. 

Issues Escape(DEVESC_ENDDOC). 
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Driver Stops the journal file. 

Driver Plays each band to the device using the Prt... interface. 

QP Closes printer DC using DevCIoseDC. 

Driver Closes printer using PrtClose. 

• PM_Q_RAW 


Component Action 

Queue processor Opens a DC for the printer using DevOpenDC and enables it 
as an OD_DIRECT device for PM_Q_RAW data. 

QP Issues Escape(DE VESC_ST ARTDOC) . 

Driver Opens the device for printing, using PrtOpen. 

QP Writes the data to the DC. 

Driver Sends the data to the device without further processing. 

The data is buffered into blocks of convenient size and 
written to the printer using PrtWrite. Control codes are sent 
to the printer using the PrtDevlOCtl commands. The size of 
the block depends on the amount of memory available to 
the device driver. 

QP Issues Escape(DEVESC_ENDDOC). 

QP Closes printer DC using DevCIoseDC. 

Driver Closes printer using PrtClose. 

• User Data Types 

The processing required for user data types depends on the format of the data 

type. In some instances it may be necessary to create a special queue 

processor to support the data type. 


SpIQpPrint 

On page 17-26, add the following note to the description: 

Note: SpIQpPrint can be interrupted by an asynchronous call, on another thread, at 
entry SpIQpControl. 


SpIQpQueryDt 

On page 17-27, change the description of the second parameter (paszDatatypes) to: 

Pointer to an array of pointers that address the locations for the returned 
names. Each location should be an array of 16 characters to accommodate the 
name and its terminating null. 


38 I/O Subsystems and Device Support 





Master Index 


© Copyright IBM Corp. 1990 


39 



40 I/O Subsystems and Device Support 



Index 


C 

category 1 , function 53H 20 
category 1 , function 73H 20 
category 4, function 50H 20 
category 4, function 56H 20 
category 5, function 4DH 21 
category 5, function 4EH 21 
category 5, function 6EH 22 
character device data stream 25 
character monitors 25 


D 

data stream monitoring 25 
dependent device driver 1 1 
DevHIp services 7 
DevHIp, MonWrite 8 
device data streams 25 
device monitor limitations 25 
device-dependent device driver 14 
device-independent device driver 1 1 
Disable_Device request 15 
Disable_Support request 13 
DispMsg 7 
DosMonReg 15 

E 

Enable_Device request 15 
error codes, field status 5 


lOCti commands (continued) 
category 4, function 50H 20 
category 4, function 56H 20 
category 5, function 4DH 21 
category 5, function 4EH 21 
category 5, function 6EH 22 
category 8, function 43H 23 
category 8, function 63H 23 

J 

job title packet 16 

K 

keystroke monitors 15 

M 

monitor dispatcher interface 16 
monitor-job title packet 17 
monitoring character device data streams 25 
monitors 

character 25 
device 25 
keystroke 15 
print 16 

MonWrite, DevHIp 8 
mouse device 1 1 
MOUSES 11 


F 

font monitor packet 16 

G 

GreCreateLogColorTable 29 
GreDeviceSetAVIOFont 31 
GreDeviceSetDCOrigin 31 
GreEscape, DEVESC_DRAFTMODE 30 
GreEscape, DEVESC_GETCP 29 
GreEscape, DEVESC_SETMODE 29 
GreGetAttributes 35 
GreQueryLogColorTable 29 
GreSetupDC 33 

I 

I DC interface descriptions 11 
INIT-Time function call summary 3 
lOCti commands 

category 1, function 53H 20 
category 1, function 73H 20 


P 

pointing device support 1 1 
print-monitor-job title packet 16 
printer timeout value 22 
Process_Absolute request 13 
Process_Packet request 12 

Q 

Query_Config request 14 
queue processor 37 

R 

Read_Disable request 15 
Read_Enable request 14 
request packets 5 
requesting an IDC interface 11 
return printer timeout value lOCti 22 


© Copyright IBM Corp. 1990 


41 



21 


set print job title lOCti 21 
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v 

VideoPause 9 


42 


I/O Subsystems and Device Support 



IBM United Kingdom 
International Products Limited 
PO Box 41, North Harbour 
Portsmouth, P06 3AU 
England 


Printed in Denmark 
Scanprint a-s, Viby J 


